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1 Purpose 

This document describes the integration effort of the mProve Download Agent into the 
Symbian operating system running on the Nokia 7650 phone. 



2 Scope 

This document outlines and discusses the software architecture of the integration process. It 
presents details on the implementations for the download agent engine, the communications 
module, the graphical user interface, the wrapper functions definitions and various changes to 
the download agent core. 
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3 User Guide 

This section presents the download agent application user guide. It describes the user 
interface with the aid of various screen shots and control settings. The order of the 
presentation follows the logical flow of the download process. 

In the user interface design follows the suggested guidelines for Nokia 7650 application 
development. Therefore, the download agent application has the look and feel of a typical 
application 

3.1 Launching the Download Agent Application 

The download agent resides in the main application area. The mProve icon identifies' the 
application for selection and launching. The figure below shows the mProve icon as it 
appears on the phone's screen and the corresponding control buttons. 
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3.2 Main View 

The main view is the first to appear on the screen after the application launch. The control 
buttons provide the options to move to other views. These views include the IP Change 
view, the Download Update view, and the About view. The Exit and Back controls terminate 
the application. The figures below show the main view, and the options available for 
selection. 
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3.3 Server Information Dialog 

The IP Change dialog presents the user with modifiable fields to edit the server name and 
port number. The OK button accepts the changes and moves to the Download Update view. 
The Cancel option terminates the application. The figure below shows the IP Change view 
and associated control buttons. 
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Enter Server Name: 
212213.43.123 

Enter Port Number: 



Ok Cancel 




3.4 Download Update View 

The download agent view presents the user with two control options only. Start initiates the 
update process, and automatically brings up the access point selection dialog. Cancel 
terminates the application. The user may cancel the application at any time. 

The different stages of the download process appear on the screen as text messages such as 
Negotiating, Verifying, Saving Block, and Complete. The progress bar keeps track of the 
time duration for the update package retrieval. Once the retrieval completes, the progress bar 
disappears and the text messages continue to appear on screen. 

Upon completion the user terminates the application with the Done button. The figures 
below show screen shots of various stages of the download process. 
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Connecting to Server... 

Negotiating... 

Verifying... 



Done 



Complete. 



3.5 About View 

The About view presents general information about the application. This information 
includes product name, version number and copyright. Options available for the view guide 
the user to either IP Change or Download Update view. The figures below show the layout 
of the view and its options. 
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3.6 Error Reporting 

There are two error-reporting mechanisms in the current implementation. First, error 
messages appear on screen in a separate dialog. The user must select OK to acknowledge the 
error and continue. 

The log file C:\bfdagent.log stores a complete history of the download agent process. This 
information can be used for debug purposes. 
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4 mProve Download Agent Architecture 

The objective is to create a download agent application for the Symbian operating system 
(OS). The application runs on the Nokia 7650 phone. The download agent application 
integrates the original mProve download agent, referred to as the core, with services provided 
by the operating system. 

The integration process involves several tasks. These tasks are as follows: 

■ Port the download agent core code to comply with operational requirements by the Symbian OS 

■ Implement the wrapper functions for the core download agent 

■ Create the sockets communications module. The communication module facilitates the download of 
update package from a remote server. A graphical user interface provides high-level control and 
monitoring of the download process. 

4.1 Major Components 

The porting process of the core download agent involves modifying the original architecture 
to comply with the operational requirements of the Symbian OS. The first requirement is to 
eliminate all modifiable globules referenced by the core agent. The second requirement, 
which stems from the fact that the Symbian OS is event driven, requires breaking a long 
running process, such as the download process, into smaller events executed in the proper 
sequence by the OS. 

The download agent Engine module solves these issues. It provides active object to step 
through the download agent process. States representing the different stages of the download 
guide the stepping processing. Another engine object includes a data structure that 
encapsulates all global variables. It initializes the data structure and maintains it throughout 
its life. Routines that reference global data are modified to accept the object owning the 
structure as augment. 

The second component is the communications module. It relies on the Symbian's sockets 
implementation. This module facilitates the communications between the download agent 
and a remote update package server. 
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The graphical user interface module provides the means for high-level control and 
monitoring of the download process. It allows the user to initiate the download process, 
modify the server information, and monitor the download through descriptive messages and 
other visual effects. 

The figure below depicts these components and their relationship with each other and the 
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operating system. The Download Agent Engine resides on top of the operating system 
EPOC. (The Symbian OS consists of EPOC and Crystal the graphical API.) The graphical 
user interface for the download agent uses the Crystal API, and provides services to the 
download engine. The Sockets engine uses the operating system to provide services to the 
download engine. The mProve Download Agent Core accesses services through the engine. 
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4.2 Download Agent Engine Module 

The download agent engine solves the operational requirements related to handling global 
variables, and making the download process event driven. In addition, it provides a logging 
mechanism for debug information, and update package storage. The engine provides 
wrapper functions to pass messages generated by the download agent and the sockets engine 
to the user interface. 

The engine consists of three objects, CBFDAgentEng, CBFDagentActive and CBFLogfile. 
The abstraction class MUINotify provides methods to access the user interface for message 
display and progress update. 

All global variables associated with the core download agent are encapsulated in 
BFDaGlobals data structures. The structure is initialized as part of creating the 
CBFDagentEng object. In turn, routines referencing global variables accept the 
CBFDagentEng object as an argument. The consequence of this implementation is to modify 
all routines utilizing global variables to accommodate an extra argument passed as a pointer 
to void. The argument is later cast to the appropriate data type for use. 

The CBFDagentEng and CBFDagentActive objects cooperate to handle the locking problem 
associated with a long running download process. The CBFDagentActive class derives from 
an/the active object base. Active objects respond to events issued by the OS. These events 
originate from requests initiated by CBFDAgentEng. Hence these two classes form a loop 
with the help of the operating system. The loop starts by a user request, and ends when the 
download process completes or the user requests to cancel. The download process is broken 
into stages. The enumeration TDagentRequest represents all stages. 

The Observer class MUINotify is part of the engine module. It defines virtual functions that 
are the bases to pass messages to the graphical user interface. 

A Simulated Flash provides an interim method to storing the update package, and other states 
that control the download and update processes. The data structure BFDaSimFlash defines 
the Flash memory. The BF DaGlobals encapsulates BF DaSimFlash. The final solution will 
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include a native Symbian device driver that resides within the operating system, and is 
accessible by the agent. 

4.3 Communications Module 

The architecture for the communications module follows the common implementation for 
sockets communications. This involves three classes CSocketsEngine, CSocketsRead and 
CSockets Write. These classes control the process of receiving and sending data. 

The CSocketsEngine is the main class responsible for creating the communications module. 
The construction of the CSocketsEngine object includes creating internal timer, collecting 
server information from user input, opening channel to the socket server, and creating the 
objects for both CSocketsRead and CSockets Write. The CSocketsEngine object provides a 
method to send data through CSockets Write. In addition, it provides access to the received 
data through the CsocketsRead. 

The communications module operates in synchronous mode. The size of data sent and 
received is set for optimal user interface performance. The engine is responsible for 
recursively requests sending and receiving data until completion. 

In the CsocketRead object, the read buffer is exposed to the download agent core through a 
shadow buffer and associated methods for reading it. Once the data is received, it gets 
copied into the shadow buffer. Reading from the shadow buffer is done through methods 
designed specifically for this purpose. The shadow buffer is circular. It operates with begin 
and end pointers to facilitate the adding and removing of data. 

4.4 User Interface Module 

The user interface module provides high-level means for the user to control and monitor the 
update package download process. 

The server name and port number are the only user data inputs required. The remaining 
controls represent the initiation and the cancellation of the download. In addition, the user 
has to terminate the application once the download is done. 
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The monitoring aspect of the user interface involves displaying messages to the user 
indicating the stage the download agent is in. Further, a progress bar indicates the elapsed 
time for the download process to complete. 

The graphical user interface module follows the standard architecture of a typical Crystal 
application. This includes applications class CmProveApp derived form CAknApplication, 
a document class CmProveDocument derived from CAknDocument. 

The CmProveAppUi object initializes all user interface views for the download agent, and 
selects the initial view. The main views are CmProveViewMain, CmProveViewAbout, 
CmProveViewDagent and CmProveDialoglPEditor. 

The main view CmProveViewMain and its dialog CmProveDialogMain provide the entry 
point for the application. The user can proceed from this view to others as desired. 

The CmProveViewAbout and its dialog CmProveDialogAbout provide general information 
about the application. This information includes application name, version and copyright. 
The user may select to move to IP Change dialog or Download Update view. 

The dialog CmProveDialoglPEditor provides the user with controls to edit the server name 
and port number. The sockets communication engine accesses this information and stores 
them internally. The user may select to proceed to Download Update view or cancel the 
download altogether. 

The final view is the heart of the download process. The view CmProveViewDagent and its 
container CmProveContainerDagent control the start, cancellation and monitor of the 
download process. They provide utilities to display messages on the screen, or store them in 
a log file. 

4.5 Core Download Agent 

Modifications targeting the core download agent resulted from the elimination of global 
variables, and breaking the long download process into small duration steps. 
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As mentioned earlier, the data structure BFJDaGlobals encapsulates all modifiable global 
variables used in the core download agent. The creation of die BFDagentEng results in the 
creation and initialization of the BFDaGlobals. The core routines access global variables 
through passing the BFDagentEng object as an argument. 

Breaking the long download process into small duration steps resulted in modification to the 
da download GetDUP 0 function. The result was several functions. The 
da_Download_GetDUP_pathl 0 function is responsible for initializations and checks prior to 
the download package download process. A typical simultaneous download and save loop is 
executed within the da Download GetDUPJoopl 0 function. The CBFDagentEng controls 
the recursive calling of the loop body. Finally, the daDownloadGetDUPErrorl 0 
function is responsible for cleanup due to exceptions occurring during the loop execution. 

4.6 Wrapper Functions Implementation 

The download agent operation depends on the proper implementation of wrapper functions. 
The wrapper functions provide parameter definitions for optimal performance. In addition, 
they provide access to device services. This section describes the implementation of these 
wrapper functions. 

4.6.1 User Interface Wrapper Functions 

The DaUI file defines wrapper function to access the screen to display messages from the 
download agent. In addition, it includes an error message translation table to display 
readable error messages 

4.6.2 Memory Manager Wrapper Functions 

The memory manager DaMemory wrapper functions rely on the standard library memory 
allocation and freeing. 
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4.6.3 Protocol Settings Wrapper Functions 

The DaSettings.C file contains parameters to control the communications protocol. The 
default parameter seems to work fine. However, changes to the MTU parameter may 
improve speed, but the 768 limit represents an optimal setting. 

4.6.4 Flash Definition Wrapper Functions 

The DaFlash DaFlashRAM files define wrapper functions for interacting with the non- 
volatile memory. The current implementation relies on simulated flash. However, the final 
implementation will include a device driver for accessing the actual flash memory. 

4.6.5 Device Definitions Wrapper Functions 



The DaDevice file contains information regarding the device, which is the Nokia 7650 
phone. The following table summarizes the type of information accessed by these routines. 



DaDevice wrapper functions description 




To return XML string describing the device. 


da_Device_GetDeviceInfo 


void da_Device_GetDeviceInfo(void *aCBFDAgentEng, char 




*cDeviceInformation); 




To return server connection address. A server address is 


daDeviceGetServerAddress 


defined as a free-form 32 byte string. 




char *da_Device_GetServerAddress(void *aCBFDAgentEng); 




To return the address in Flash memory to use when saving an 




update package. See the Notes for more specific information. 


daDeviceGefUpdatePackageAddress 




unsigned int da_Device_GetStateAddress(void 




*aCBFDAgentEng ); 




To return the address in Flash to use for backing up updated 


daDeviceGetBackupAddress 


Flash banks. 




unsigned int da_Device_GetUpdatePackageAddress(void 




♦aCBFDAgentEng, unsigned int uiDUPsize, unsigned int 
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DaDevice wrapper functions description 



uiStateSize); 



daDeviceGetStateAddress 



Obtain the address of the update state. 

unsigned int da_Device_GetBackupAddress(void 
♦aCBFDAgentEng, unsigned int uiSize); 



da Device GetStateActiveValue 



To obtain the value of the active update state, 
unsigned int da Device GetStateActiveValue(void); 



unsigned int daDeviceYield(void); 



unsigned int da_Device_GoOffline(void); 



void da_Device_KickWatchdog(void); 



void da_Device_Reset(void); 



void da_Device_Sleep(void * aCBFDAgentEng, int 
milliseconds); 

bfuquad da_Device_GetMillisecondTick(void 
♦aCBFDAgentEng); 



i DeviceSimultaneousDownloadAndSave 



To obtain the option of the simultaneous download and save 
bool daDeviceSimultaneousDownloadAndSave(void); 



da_Device_AllocatedDownloadBufferSize 



To obtain the size of the allocated buffer for the simultaneous 
download and save. This function call is valid only if 
da Device SimultaneousDownloadAndSaveO returns true 
unsigned int da_Device_AllocatedDownIoadBufferSize(void); 



bool da_Device_PackagePlacementForward(void); 



int da_Device_BatteryStatus(void); 



daDeviceSaveDownloadStatus 



To save the current download status into the non-volatile 
memory. The download status will be used if a lost connection 
needs to be resumed. 

void da Device SaveDownloadStatus(void *aCBFDAgentEng, 
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DaDevice wrapper functions description 

char *ptrMem, unsigned int uiSize); 

To obtain the download status from the non-volatile memory. 
da_Device_SaveDownloadStatus int da_Device_RetrieveDownloadStatus(void 

♦aCBFDAgentEng, char *ptrMem, unsigned int uiSize); 

4.6.6 Bearer Definitions Wrapper Functions 

The DaBearer file contains a routine for selecting the bearer type, and issuing the proper 
instructions to interact with it. The bearer type for this implementation is TCP/IP. The 
bearer wrapper functions provide access to the sockets engine module through intermediate 
mediate routines. The bfbearerlib_tcpip.c and bfcomdrvtcpip.cpp files define the 
intermediate layers. These intermediate steps are for the purpose of maintaining consistency 
with the original download agent implementation. 



The contents of this material are confidential and proprietary to Bitfone Corporation and may not be 
reproduced, published, or disclosed to others without the prior written consent of Bitfone. 
© 2002 Bitfone Corporation. 



-20- 



Bitfone __ 

mProve Download Agent Integration Code Date: 1 0/1 7/2002 

Architecture For The Nokia 7650 



5 Implementation 

5.1 Graphical User Interface 

5.1 .1 Overview of Graphical User Interface Module 

The graphical user interface consists of several objects representing the different views 
shown to the user. These views provide the means to control and monitor the download 
process. 

The agent application follows the standard Crystal structure for user interface. It includes an 
object for the application class CmProveApp derived from CAknApplication, and an object 
for a document class CmProveDocument derived from CAknDocument. 

The CmProveAppUi class is responsible for initializing and displaying the different views on 
the Nokia 7650 phone display. The figure below describes this object and its relationship to 
the rest of the application. The CmProveAppUi class is derived from CAknViewAppUi. It 
uses four objects to construct the different views. These objects are CmProveViewMain, 
CmProveViewDagent, CmProveDialoglPEditor, and CmProveViewAbout. 

The CmProveViewMain and CmProveViewAbout classes have dialog objects. These objects 
are CmProveDialogMain and CmProveDialogAbout, respectively. The view objects are 
responsible for updating the display with their data. The dialog objects are responsible for 
storing and maintaining the data associated with each view. 

The CmProveDialoglPEditor object allows the user to enter the desired server information. 
Its implementation is rather unique, where it does not have a view. The server information 
collected by this dialog is stored directly into the CmProveAppUi object. On the other hand, 
CmProveAppUi object provides the same information for the CmProveDialoglPEditor to 
initialize its data upon display. 

The CmProveViewDagent class controls the download processes. It is derived from 
CAknView and MUInotify classes. The MUInotify is an abstract class. It provides through 
CmProveViewDagent class methods for the download application to display and monitor the 
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progress of the download process. The view object owns iContainer and iLogfile objects. 
The iLogfile object provides a mean to store messages for debug purposes. 

The container class CmProveContainerDagent owns several objects. These objects represent 
the download agent engine CBFDagentEng and CBFDagentActive, and the communications 
module CSocketsEngine. In addition, the container owns objects for message display and 
progress bar. 

The following diagrams describe the different objects that make up the user interface. The 
relationship between these objects and other download agent's modules is illustrated. 
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CmProveViewDagent 

iLogfile 

iContainer 



MUlNotify 



CBFLogfile 



CmProveContainerDagent 

iAppView 

iBFDagentEng 

iBFDagentActive 

iSocketsEngine 

iPBar 



MUlNotify 



CBFDagentEng 



MCoeControlObserver 



CBFDagentActive 



CSocketsEngine 



CEikProgressInfo 
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5.1.2 CmProveAppUi 



Class CmProveAppUi : public CAknViewAppUi 



An instance of class CmProveAppUi is an object that uses several v 
download agent applications. 



n objects to create the user interface for the 



Performs second phase construction of the object, 
void ConstructLO; 



SetPortNumber 



Free up resources associated with the object. 
-CmProveAppUiO 



Sets the private data member iServer to the desired name identified by aServerNm. 
void SetServerName(TDesC& aServerNm); 



Sets the private data member iPort to the desired port number identified by aPortNo. 
void SetPortNumberfTInt aPortNo ) 



h private data member iServerNM. 



TDesC& ServerNameO; 



HandleCommandL 



Return port number associated with private data member iPortNo. 
Tint PortNumberO 



Handles user driven events in relationship to user interface. Commands are defined 
in the resource file. 



void HandleCommandL(TInt aCommand) 



Handles key events associated with the user interface. 
HandleKeyEventL virtual TKeyResponse HandleKeyEventL( const TKeyEvent& 

aKeyEvent.TEventCode aType); 



Holds the address of the navigation pan control. 
CAknNavigationControlContainer* iNaviPane 



iDecoratedTabGroup 



Holds the address of the navigation decorator. 
CAknNavigationDecorator* iDecoratedTabGroup 
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Class CmProveAppUi 


: public CAknViewAppUi 




Holds the address of the tab group, which is read from the resource file. 


iTabGroup 


CAknTabGroup* iTabGroup 




Stores the destination server name. 


iServerName 






TBuf<KMaxLengthServerName> iServerName 




The destination port number. 


iPortNumber 




Tint iPortNumber; 


KMaxLengthServerName 


Static variable that holds the maximum string length for the server name 
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5.1.3 CmProveViewMain 



Class CmProveViewMain : public CAknView 


An instance of class CmProveViewMain is an object responsible for the display of the Main view. The ( 
displayed are maintained in the dialog object,CmPorveDialogMain. 


lata to be 


ConstructL 


Perform second phase construction of the CmProveViewMain object, 
void ConstructLO 




Destructor 


Destroy this object releasing all resources owned by the object. 




-CmProveViewMain () 




Id 


Returns the view identification number. 




TUid ld() const; 






Handle user driven events in relationship to user interface. Commands an 


: defined 


HandleCommandL 


in the resource file. 

void HandleCommandL(TInt aCommand) 




HandleClientRectChange 


Update the view content to match the display screen, 
void HandleClientRectChange() 






Create and display the Main dialog view object. 




DoActivateL 


void DoActivateL(const TVwsViewId& aPrevViewId.TUid aCustomMessageld, 
const TDesC8& aCustomMessage) 


DoDeactivate 


Destroy and hide the Main dialog view object from the screen, 
void DoDeactivateO 




iContainer 


Reference to the dialog object of the Main view. 
CmProveDialogMain* iContainer 
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5.1.4 CmProveViewDagent 



Class CmProveViewDagent : public CAknView , public MUlNotify 


An instance of class CmProveViewDagent is an object responsible for the display of the Download Update view. 
This class has a container class. It owns a CBFLogfile object for storing debug information. 


Constructor 


Creates CmProveViewDagent object as default constructor 


CmProveViewDagentO, 


NewL 


Construct a CmProveViewDagent object using two phase construction and returns a 
pointer to the object. 

static CmProveViewDagent* NewL(); 


NewLC 


Construct a CmProveViewDagent object using two phase construction, pushes the 
object onto the cleanup stack, and returns a pointer to the object. 

static CmProveViewDagent* NewLC(); 


ConstructL 


Perfoms second phase construction of the CmProveViewDagent object. 


void ConstructLO; 


Destructor 


Destroy this object and release all resources owned by it. 
~CmProveViewDagent(); 


UpdateCbaL 


Alters the definition of the CBA based on the current context, 
void UpdateCbaL(TInt aResourceld); 




Create, display and destroy utilities for the progress bar. 




void CreateProgressBarsL(); 


Progress Bar Control 


void DeleteProgressBarsLO; 


Utilities 


void IncrementBarsAndDraw(TInt increment); 

void ResetAllValuesO; 

void SetFinalValue(TInt aFinalValue); 


Id 


Returns the identification number of the download agent view. 
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Class CmProveViewDagent : public CAknView , public MUlNotify 


TUid Id() const; 




Handle user driven events in relationship to user interface. The resource file defines 


HandleCommandL 


these commands. 




void HandleCommandL(TInt aCommand) 




Update the view content to match the display screen. 


HandleClientRectChange 


void HandleClientRectChangeO 




Create and display the Main dialog view object. 


DoActivateL 


void DoActivateL(const TVwsViewId& aPrevViewId.TUid aCustomMessageld, 




const TDesC8& aCustomMessage) 




Destroy and hide the Main dialog view object from the screen. 


DoDeactivate 




void DoDeactivate() 




Wrapper function to container method ShowTextOnScreen. 


Write 




void Write(const TDesC &aMsg); 




Wrapper function to container method ClearScreen. 


ClearScreen 




void ClearScreenO; 




Execute HandleCommandL method using the passed argument. 


NextCommand 




void NextCommand(TInt aCommand); 




Wrapper function to display mTest results on screen. 


mtAgentTestShowResult 


void mtAgent_TestShowResult( TUint8 aPort, Tint aRetCode, TDes8 &aMsg ); 




Write messages to log file iLogfile. The method overload is for handling different 




types of arguments 




void PrintNotify(const TDesC& aDes, TUint aFontStyle = 0); 


Write to Log File Utilities 


void PrintNotify(const TDesC8& aDes, TUint aFontStyle = 0); 




void PrintNotify(TInt aNumber); 




void ErrorNotify(const TDesC& aErrMessage, Tint aErrCode); 
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Class CmProveViewDagent : public CAknView , public MUlNotify 





Write messages to screen. The method overloaded is for handling different types of 




arguments 


Write to screen utilities 


void PrintToScreen(const TDesC& aDes, TUint aFontStyle = 0); 




void PrintToScreen(const TDesC8& aDes, TUint aFontStyle = 0); 




void PrintToScreen(TInt aNumber); 




Write to screen wrapper for the download agent core user interface. 




void myPrint_char(const char aStr); 


Write utilities for integration void myPrint_str(const char *aStr); 


with download agent. 


void myPrint_str_vaI(const char *aStr, unsigned int aValue); 




void myPrint_str_2val(const char *aStr, unsigned int aValuel, unsigned int 




aValue2); 


PrintBinary 


Write server communications into a log file iDatfile for debug purposes- 


void PrintBinary(const TDesC8& aDes); 




Writes communications module state change into the log file iLogfile. 


SetStatus 




void SetStatus(const TDesC& aStatus); 




Issues cancel request for the communications module. This will initiate the proper 


CancelRequest 


shutdown sequence for resources associated with socket communications. 




void CancelRequest(); 


iLogfile 


The log file object 


CBFLogfile* iLogfile; 




The server communications data file object 


iDatfile 




CBFLogfile* iDatfile 




Holds pointer to the container of the download agent object. 


iContainer 




CmProveContainerDagent* iContainer 
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5.1.5 CmProveViewAbout 



Class CmProveViewAbout : public CAknView 



An instance of class CmProveViewAbout is an object responsible for the display of the About view. The container 
object CmProveDialogAbout maintains the data for the view. 



Perform second phase construction of the CmProveViewAbout object, 
void ConstructLQ 



Destroy this object releasing all resources owned by the object. 
-CmProveViewAboutO 



Returns the view identification number. 
TUid Id() const; 



Handles user driven events in relationship to user interface. The resource file 
defines these commands. 



HandleCommandL 



void HandleCommandL(TInt aCommand) 



HandleClientRectChange 



Update the view content to match the display screen, 
void HandleClientRectChangeO 



Create and display the dialog view object. 

void DoActivateL(const TVwsViewId& aPrevViewId,TUid aCustomMessageld, 
const TDesC8& aCustomMessage) 



Destroy and hide the dialog view object from the screen, 
void DoDeactivateQ 



Stores reference to the container. 
CmProveDialogAbout* iContainer 
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5.1.6 CmProveDialogMain 



Class CmProveDialogMain : 


: public CEikDialog 


An instance of class CmProveDialogMain is an object that maintains data for the CmProveViewMain view object. 




Destroy object releasing all resources it owns. 


Destructor 




~ CmProveDialogMain 0 




Defines the layout of the dialog window before it is displayed. 


PreLayoutDynlnitL 


The resource file defines the layout. 




void PreLayoutDynlnitLO 




Called by Symbian framework when the OK button is-pressed. 


OkToExitL 




TBool OkToExitL( Tint aButtonld ) 
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5.1.7 CmProveDialoglPEditor 



Class CmProveDialoglPEditor : public CAknDialog 



An instance of class CmProveDialoglPEditor is an object is responsible for creating and displaying the dialog for 

the object. The object provides to modify the server name and port number by the user. Modified data are stored 

in the application user interface object CmProveAppUi. 

Construct CmProveDialoglPEditor object with aAppUi using two-phase constructor 

NewL and return a pointer to the object. 

static CmProveDialoglPEditor* NewL(CmProveAppUi& aAppUi) 

Construct CmProveDialoglPEditor object with aAppUi using two-phase constructor, 

NewLC P ush ^ e ob j ect onto * e cleanup stack, and return a pointer to the object. . 

static CmProveDialoglPEditor* NewLC(CmProveAppUi& aAppUi) 

Display and run the dialog. Return zero if dialog was cancelled, otherwise returns the 

ExecuteLD 10 of button that closed dialog. 

Tint ExecuteLD() 

Perform second phase construction of the object. 

Constructor 

void ConstructLO 

Destroy this object and free up any resources owned by it. 

Destructor 

-CmProveDialoglPEditorO 

Return a pointer to the Application user interface AppUi object. 

AppUi 

CmProveAppUi& AppUi() const; 

Called by Symbian framework when the OK button is pressed. 

OkToExitL 

TBool OkToExitL(TInt aKeycode); 

Copy text described by aText into an edit window type control defined by aControl. 

SetTextL 

void SetTextL(TInt aControl, const TDesC& aText); 

_ _ T . Copy number described by aNumber into an edit window type control defined by 

SetNumber 
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Class CmProveDialoglPEditor : public CAknDialog 



void SetNumber(TInt aControl, Tint aNumber) 



Copy text defined in an edit window type control aControl into aText. 
void GetText(TInt aControl, TDes& aText) 



Return number defined in an edit window type control aControl. 
Tint GetNumber(TInt aControl) 



void PreLayoutDynlnitLO; 



SaveSettings 



Save server name and port number into data members of CmProveAppUi. 
void SaveSettingsQ; 



Holds a reference to CmProveAppUi object. 
CmProveAppUi& iAppUi; 
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5.1.8 CmProveContainerDagent 



Class CmProveContainerDagent : public CCoeControl, MCoeControlObserver 

An instance of class CmProveContainerDagent is an object for storing and maintaining the data for the 
CmProveViewDagent view. The container object includes display mechanism for text and progress bar. In 
addition, the container owns several objects including the download agent engine, and communications module. 

Perform second phase construction of the object. 

ConstructL 

void ConstructL(const TRect& aRect, MUTNotify AaAppView); 
Destroy this object releasing all resources it owns. 

Destructor 

-CmProveContainerDagentO; 

Display text information about the download state on the screen. The aText 
ShowTextOnScreen argument defines the state. 

void ShowTextOnScreen(const TDesC& aText); 



Wrapper to the ShowTextOnScreen method, 
void Print(const TDesC& aText); 



Advances the current screen position to a new line, 
void PrintNewLineLQ; 



Clears screen from all text, 
void ClearScreenO; 



IncrementBarsAndDraw 



Increments the progress bar by alncrement value, 
void IncrementBarsAndDraw( Tint alncrement ); 



ResetAHValues 



Resets the progress bar value to zero, 
void ResetAllValuesQ; 



CreateProgressBarsL 



Create progress bar object, and display it on the screen, 
void CreateProgressBarsLO; 



Sets the final value of the progress bar. 
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Class CmProveContainerDagent : public CCoeControl, MCoeControlObserver 


void SetFinalValue(TInt aFinalValue); 




Destroy the progress bar object, and remove it from the screen. 


DeleteProgressBarsL 


void DeleteProgressBarsLO; 




Respond to size changes of component objects. This function is called in part 


IZ£ 3118 


of the Symbian framework. 




void SizeChanged() 




Returns the number of controls in a compound control. This function is 


CountComponentControls 


called in part of the Symbian framework. 




Tint CountComponentControlsO const; 




Returns control from a compound control referenced by its ID. This function 


ComponentControl 


is called in part of the Symbian framework. 




CCoeControl* ComponentControl(TInt alndex) const; 




Draw the screen with active controls. The windows server calls this function. 


Draw 






void Draw(const TRect& aRect) const; 




Container for messages to be displayed on screen. 


iTextLines 




RArray <CEikLabel*> iTextLines 




Stores pointer to progress bar object. 


iPBar 




CEikProgressInfo* iPBar 




Stores pointer to communications engine object. 


iSocketsEngine 


CSocketsEngine* iSocketsEngine 




Stores pointer to download agent engine object. 


iBFAgent 


CBFDagentEng* iBFAgent 




Stores pointer to download agent active object. 


iBFDAgentActive 


CBFDagentActive* iDAgentActive 
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5.1.9 CmProveDialogAbout 



Class CmProveDialogAbout : public CEikDialog 


An instance of class CmProveDialogAbout is an object to store and maintain data for the CmProveViewAbout 


object. This information includes name, version and copyright. 




Destroy this object releasing all resources owned by the object 


Destructor 


-CmProveDialogAboutO 




Defines the layout of the dialog window before it is displayed. The resource file 


PreLayoutDynlnitL 


defines the layout. 




void PreLayoutDynlnitLO 




Called by Symbian framework when the OK button is pressed. 


OkToExitL 




TBool OkToExitL( Tint aButtonld ) 
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5.2 mProve Download Agent Engine 

5.2.1 Overview of mProve Download Agent Engine 

The download agent engine consists of several objects. These are CBFDagentEng, 
CBFDagentActive, MUINotify and CBFLogfile. 

The CBFDagentEng object is derived from Cbase. It owns the global data structure 
iBFDagentEngThis, the iDupfile object for storing the update package. In addition, the 
object uses an observer object iAppView and a communications engine object. 

The CBFDagentActive object is derived from CActive. It uses a iServiceProvider object of 
type CBFDagentEng. 

Both CBFDagentEng and CBFDagentActive objects control the download process with the 
aid of internal state trackers iDagentRequest and iDActiveRequest. The enumeration 
TDagentRequest defines these states. 

The following diagram identifies the download agent engine objects. It describes their 
relationship with each other and the remainder of the application. 
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5.2.2 CBFDagentEng 



Class CBFDagentEng : public Cbase 

An instance of class CBFDagentEng is an object responsible for executing the download agent process in the 
proper order. The object owns iBFDagentEngThis global data structure, and iDupfile for storing the update 
package. 

Construct a CBFDagentEng object with CsocketsEngine aNetwork, and observer 
Constructor aAppView. This is the first phase of two-phase object construction. 

CBFDagentEng(CSocketsEngine *aNetwork, MUINotify &aAppView); 

Construct a CBFDagentEng object with CsocketsEngine aNetwork, and observer 
aAppView using two-phase object construction. Returns a pointer to the object. 

NewL 

static CBFDagentEng* NewL(CSocketsEngine &aNetwork, MUINotify 
&aAppView) 

Construct a CBFDagentEng object with CsocketsEngine aNetwork, and observer 
aAppView using two-phase object construction. Push the object onto the cleanup 
NewLC stack. Returns a pointer to the object. 



static CBFDagentEng* NewLC(CSocketsEngine &aNetwork, MUINotify 
&aAppView) 





Perfoms second phase construction of the CBFDagentEng object. 


ConstructL 




void ConstructL(); 




Destroy this object and release all resources owned by it. 


Destructor 




~CBFDagentEng(); 




Controls the transition between the different stages of the download process. It 




works in conjunction with an active object. 


RequestTheService 


void RequestTheService( TDagentRequest aDActiveRequest, TRequestStatus& 




aStatus); 


CancelServiceRequest 


Cancels the download process, by performing proper cleanup procedure. 




void CancelServiceRequest(); 


GetDUPDone 


Returns true if the update package download is complete, otherwise it returns false. 
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Class CBFDagentEng : public Cbase 



TBool GetDUP_Done(); 



Writes the data update package into a file iDupfile. 
void writeDUPfile(char *iDupBuffer, TUint size); 



iBFDAgentEngThis 



Holds a pointer to BFDaGlobals data structure. 
TAny *iBFDAgentEngThis; 



Stores pointer to Communications engine object. 
CSocketsEngine *iNetwork; 



Stores reference to Observer. The observer provides mechanism for printing 
messages, both to screen and log file. 



iAppView 



MUINotify &iAppView; 



iDupFile 



Stores pointer to Object of type CBFLogfile for storing the update package. 
CBFLogfile * iDupfile; 



bConnectionEstablished 



The state of connection with server. 
TBool bConnectionEstablished; 



uiDownloadSize 



The update package size. 
Tuint uiDownloadSize; 



Keeps track of error state during the download process. This is necessary because 
control shifts between the active object and this object. 



RequestTheServiceErrorFlag 



TBool RequestTheServiceErrorFlag; 



The state of download agent request. 
TDagentRequest iDagentRequest; 



RTimer resource. 
RTimer iTimer; 



Timer request status. 
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Class CBFDagentEng 


: public Cbase 


TRequestStatus timerStatus; 




Current time information. 


time 






TTime time; 
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5.2.3 CBFAgentActive 



class CDAgentActive : public CActive 



An instance of class CDAgentActive is an active object responsible for executing the download process. Different 
stages execute based on events driven by the operating system. The event initiation is performed by the download 
agent engine object iServiceProvider. 

Construct CDAgentActive object with observer aServiceProvider. This is the first 
Constructor phase of two-phase object construction. 



CDAgentActive(CBFDagentEng* aServiceProvider); 



Construct CDAgentActive object with observer aServiceProvider using two-phase 
object construction. Pushes object onto cleanup stack. Returns pointer to the object. 

static CDAgentActive* NewL(CBFDagentEng* aServiceProvider); 



Performs second phase construction, 
void ConstructLQ ; 



IssueRequest 



Destroy object and release all resources owned by it. 
-CDAgentActiveO; 



Issue request to execute the different stages of the download process. The request is 
issued for the iServiceProvider object with the appropriate request state. 



void IssueRequest(TDagentRequest zRequest); 



Process Cancel request, with appropriate cleanup procedure. Implementation of the 
virtual Cancel method for the active object. 



Returns the true if object is already canceled, otherwise returns false. 
TBool CanceledO; 



Performs specific procedure pertaining to the cancel request, 
void DoCancel(); 



Controls the execution of different stages of the download process. The framework 
calls this function, once the active object state changes to pending. 
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class CDAgentActive 


: public CActive 


void RunLQ; 




Download agent engine object. 


iServiceProvider 




CBFDagentEng* iServiceProvider 


iDActiveRequest 


Request state for active object. 


TDagentRequest iDActiveRequest; 



The contents of this material are confidential and proprietary to Bitfone Corporation and may not be 
reproduced, published, or disclosed to others without the prior written consent of Bitfone. 
© 2002 Bitfone Corporation. 



-44- 



Bitfone __ 

mProve Download Agent Integration Code Date: 1 0/1 7/2002 

Architecture For The Nokia 7650 

5.2.4 Update Request States 
enum zTDagentRequest 

Enumeration representing the different states the download agent process goes through. These states coordinate 
the execution of the download process between the agent engine object and the active object. 

EBf_AgentStart 

EBfAgentConnect 

EBf_AgentGetSizeInfo 

EBf_AgentDownloadPackage 

EBf_AgentRelease 

EBf_AgentDisconnect 

EBf_AgentVerify 

The Request State 

EBf_AgentCommit 
EBf_AgentFree 
EBf_AgentSuccess 
EBf_AgentCancel 
EBf_AgentGetDUP_loop 1 
EBfBadDagentRequest 
EBfBadDagentCancelRequest 
EBf_AgentStart_Complete 
EBfAgentConnectComplete 
EBf_AgentGetSizeInfo_Complete 
Request Complete State EBfAgentDownloadPackageComplete 
EBf_AgentRelease_Complete 
EBfAgentDisconnectComplete 
EBf_AgentVerify_Complete 
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enum zTDagentRequest 

EBfAgentCommitComplete 
EBf_AgentFree_Complete 
EBfAgentSuccessComplete 
EBf_AgentCancel_Complete 
EBf_AgentGetDUP_loopl_Complete, 
EBf_BadDagentStatus , 
EBfAgentStartError, 
EBfAgentConnectError, 
EBfAgentGetSizelnfoJError, 
EBfAgentDownloadPackageError, 
EBf_AgentRelease_Error, 
EBfAgentDisconnectError, 
Request Error State EBf_AgentVerify_Error, 
EBf_AgentCommit_Error, 
EBf_AgentFree_Error, 
EBfAgentSuccessError, 
EBf_AgentCancel_Error, 
EBf_AgentGetDUP_loop l_Error, 
EBf_BadDagentError 
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5.2.5 CBFLogfile 



class CBFLogfile : public RFile 



An instance of class CBFLogfile is an object, which is used to create instances for log files. 

File session resource. The session is usually handled by the operating system. 
fsSession However, it was added here for completeness. 



File handle resource. 
RFile fp; 



Construct a CBFLogfile object. The first stage of two-phase construction. 
CBFLogfile(); 



Destroy object and releases all resources owned by it. 
-CBFLogfile(void); 



Performs second phase construction with a file name representing the full path and file 
name. 



void ConstructL(TDesC& filename); 



Writes to log file TdesC message, 
void Write(const TDesC& message); 



Writes to logfile TdesC8 message, 
void Write(const TDesC8& message); 



Buffer holding full qualifying file name. 
TBuf<256> iFileName; 
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5.2.6 BFDaGlobals 



struct BF_DaGlobals 



An instance of class BF DaGlobals is an object, which contain all global variables associated with the download 



engineSupport 



Holds point to CBFDagentEng object, 
void *engineSupport 



bool bStatelnitialized 
UpdateStateDescriptor USD 
char *cptrDUP 
unsigned int uiDUPSize 
unsigned int uiDUPCRC 
bool bChannelOpenned 
bool bProtocolStarted 
DownloadMEM zDownloadMEM 
unsigned char *cPayload 
unsigned int uiProtocolMTU 
char *cptrTest 



bool bDisplayProgressBar; 

unsigned int uiProgressBarSizeElapsed; 

UIRFields UIRInformation 



unsigned char cCurrentFrameNumber 

unsigned int uiPathMTU 

unsigned char cRecvBufTRECVBUFFERSlZE] 

unsigned int uiRecvBufldx 

int iRecvBufLimit 
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struct BF_DaGlobals 

unsigned int uiSleepRIT 
CRC unsigned long *da_crc_table; 

volatile unsigned char *da_heap_heapBegin; 
unsigned long da_heap_ulHeapMemoryBegin; 
bool daheapbHeapMemorySPShared; 





uns 


gned long da_heap_ulHeapMemoryLimit; 


Heap 


uns 


gned int da heap heapCounter malloc 


uns 


gned int da heap heapCounter free 




uns 


gned int da_heap_heapCounter_realloc 




uns 


gned int da_heap_heapCounter_calloc 
gned int da heap heapCounter totalmem 




uns 


gned int daheapheapCountermaxmem 



int sendcnt 
int receive cnt 





int recvbufpos 


mTest 




int recvbuflimit[5] 




unsigned char SendBufferStr[5][200] 




unsigned char RecvBufferStr[5][200] 




bool da_debug_feedback 




char da_debug_buffer[128] 


Debug 




bool dadebugramfeedback 




char da_debugram_buffer[128] 


Bearer 


da bearer type da bearer selected 


Progress Bar 


unsigned int progress_full_scale 
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struct BF_DaGlobals 




BfFlashLib_This *bfflashlib 


Simulated flash, ram 


char *FIashSimulated 




char *RAMSimulated 


da_Download_GetDUP_path 1 


char *GetDUP_cptrStoreBuffer 
bool GetDUP_bFirstSegment 
bool GetDUPDone 
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5.2.7 Simulated Flash and RAM 
struct BF_DaSimFlash 

An instance of struct BF_DaSimFlash is an object representing the simulated Flash and RAM memory. This 
would be replaced with an interface to writing directly to the flash. 

unsigned int dt device flashbase 

unsigned int dtdeviceflashsize 

unsigned int dt device flashblocksize 

unsigned int dt device flashwaitclock 

unsigned int dt device stateaddress 

unsigned int dt_device_updatepackageaddress 

unsigned int dt device backupaddress 

unsigned int dt device updatestatus 

unsigned int dt_device_rambase 

unsigned int dt device ramsize 
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5.2.8 MUlNotify 


class MUlNotify 


MUlNotify is an abstract c 


lass specifying methods for screen display, creating log files and manipulating progress 


bar. 






virtual void rnntNotiry(const iuesc& aivlessage, l uint aAlu ibutes — i)) — 




virtual void PrintNotify(const TDesC8& aMessage, TUint aAttributes = 0) = 0; 


Writes to log file 


virtual void PrintBin (const TDesC8& aDes) - 0 - 
inary cons 




virtual void PrintNotify(TInt aNumber) = 0; 




virtual void ErrorNotify(const TDesC& aErrMessage, Tint aErrCode)^ 0; 




virtual void CreateProgressBarsLO = 0; 




virtual void IncrementBarsAndDraw(TInt increment) 0, 


Progress Bar Controls 


virtual void SetFinalValue(TInt aFinalValue) — 0; 




virtual void ResetAllValues() = 0; 




virtual void DeleteProgressBarsLO = 0; 




Prints the status of communications module. 


SetStatus 






virtual void SetStatus(const TDesC& aStatus) = 0; 




Clear text from screen. 


ClearScreen 






virtual void ClearScreen() = 0; 




Updates command buttons 


UpdateCbaL 


virtual void UpdateCbaL(Tlnt aResourceld) = 0; 




Cancel request for download process 


CancelRequest 


virtual void CancelRequest() = 0; 
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5.3 MProve Download Agent Core 

The primary change to the download agent involved changing argument passing to certain 
functions. These functions access global variables, which are made available through a data 
structure owned by the download agent engine. 

In addition, the da Download GetDUP function is modified to accommodate event drive 
framework. The function was modified to perform the package retrieval in multiple steps 
with shorter time duration. The following table lists the new functions and describes their 
role in the download process. 



Download Agent Process 

Changes made to the download agent core to improve responsiveness of the application under event driven 
architecture of the Symbian operating system 

Gateway function to separate the process of downloading the update packet 
da Download GetDUP into simultaneous download and save, and one shot download. 

int da_Download_GetDUP(void *aCBFDAgentEng) 

Initiates the process of download and save of the update packet. 

da Download GetDUPpathl 

int da_Download_GetDUP_pathl (void *aCBFDAgentEng) 

Executes a single loop of the download process. This approach places the 

da_Download_GetDUP_loop 1 role of recursive execution to the calling function. 

int da_Download_GetDUP_loopl(void *aCBFDAgentEng) 
Handles exceptions by freeing resources allocated for the download 

da_Download_GetDUP_Errorl process. 

int da_Download_GetDUP_Errorl (void *aCBFDAgentEng) 
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5.4 Communications 

5.4.1 Overview of Sockets Communications 

The communications module consists of three main objects. These objects are 
CSocketsEngine, CSocketsRead and C Sockets Write. 

CSocketsEngine is the main object in the communications module. The object owns the 
sockets read and write objects. In addition, it owns an iTimer object to keep track of time 
during communication sessions. The object uses an observer class iConsole to send messages 
for display and storage in log files. 

The CSocketsRead class is responsible for receiving data from the server and making it 
available to the download agent core. An object of this class owns an iTimer object, and uses 
iConsole observer for message printing. The object moves the received data into a secondary 
circular buffer, also known as the shadow buffer. The download agent accesses this buffer to 
get the required data. 

The CSockets Write class is responsible for sending data to the server. An object of this class 
owns an iTimer object, and uses iConsole object for message printing. 

The CtimeOutTimer class is derived from CTimer. Its purpose is to keep of track of time for 
time-outs detection. 
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MTimeOutNotif 



CSocketsEngine 



i Socket 

iSocketServ 

iResolver 

iConsole 

iSocketsRead 

iSocketsWrite 

iTimer 



MUINotify 



CSocketsWrite 



CTimeOutTimer 



MTimeOutNotif 



MTimeOutNotif 



i Socket 
iRecvBuffer 
iConsole 
iTimer 



MUINotify 



CTimeOutTimer 



CSocketsWrite 



iSocket 

iConsole 

iTimer 



MUINotify 



CTimeOutTimer 
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5.4.2 CSockets Engine 



class CSocketsEngine : public MTimeOutNotify 



An instance of class CSocketsEngine is an object responsible for creating the communications module. This 
includes creating a separate sockets reader and writer objects. In addition, it initializes the receive buffers. 

Create CsocketsEngine object with observer aConsole using two-phase construction. 

Constructor 

CSocketsEngine(MUINotify& aConsole) 

Create CsocketsEngine object with observer aConsole, using two-phase construction. 
NewL Return pointer to object. 



Socket Connect 



static CSocketsEngine* NewL(MUINotify& aConsole) 



Create CsocketsEngine object with observer aConsole, using two-phase construction. 
Push the object onto the cleanup stack. Returns pointer to object. 

static CSocketsEngine* NewLC(MUTNotify& aConsole) 



Destroy object and all resources owned by it. 
~CSocketsEngine(); 



Perform second phase construction of the CsocketsEngine. This includes creating 
objects for sockets reading and writing. 



void ConstnictL(); 



First stage of establishing socket connection. It handles establishing connection with 
IP address, or domain name. Performs lookup procedure in case of domain name. 

void ConnectL() 

Establish connection directly with IP address, 
void ConnectL(TUint32 aAddr) 

Performs the connection procedure in synchronous fashion, 
void SyncConnectQ 



Returns the state of socket connection. 
TBool ConnectedQ const; 



The contents of this material are confidential and proprietary to Bitfone Corporation and may not be 
reproduced, published, or disclosed to others without the prior written consent of Bitfone. 
© 2002 Bitfone Corporation. 

-56- 



Bitfone 



mProve Download Agent Integration Code 
Architecture For The Nokia 7650 



Date: 10/17/2002 



class CSocketsEngine : public MTimeOutNotify 





Performs domain name looku in a s nchronous fashion 
e orms omain name oo up in a sync 


Sync_LookupL 




void Sync LookupLO; 




Closes connection, and performs cleanup procedure. 




void Disconnect); 


Socket Disconnect 




Performs the disconnection procedure in synchronous fashion. 




void sync DisconnectO; 




Set server name with aName. 


SetServerName 






void SetServerName(const TDesC& aName); 




Returns the server name. 


ServerName 






const TDesC& ServerName() const; 




Set the port number with aPort. 


SetPort 




void SetPort(Tlnt aPort); 




Return the port number. 


Port 




Tint PortO const; 




Read sockets receive buffer 


Read 






void Readf); 




Write aData string to send buffer 


WriteL 




void WriteL(const TDesC8& aData); 




Cancel outstanding socket requests. Perform cleanup procedure. 


Cancel 


void Cancel(); 




States describing the different stages of socket communications. 




ENotConnected, 


TSocketsEngineState 


EConnecting, 




EConnected, 
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class CSocketsEngine : public MTimeOutNotify 





ETimedOut, 




ELookingUp, 




ELookUpFailed, 




EConnectFailed, 




„ . 

^Disconnecting 




Change socket status, iEngineStatus. Prints state change to log file as well. 


ChangeStatus 


void ChangeStatus(TSocketsEngineState aNewStatus)* 




Print debug information to log file. 


Print 




void "nnt^ const iDesUoc aues); 




Wrapper function to access the receive shadow buffer. 


RecvMessageNoBIockL 


TUint RecvMessageL(char *aMessage, unsigned int aLength); 




TUint RecvMessageNoBlockL(char *aMessage, unsigned int aLength); 




Reset receive shadow buffer 


ResetRecvBuffer 






void ResetRecvBufferO; 




- 

Object current status 


iEngineStatus 


TSocketsEngineState iEngineStatus 




Observer to print messages 


iConsole 






MUINotify& iConsole 




Socket reader object 


iSocketsRead 




CSocketsRead* iSocketsRead 




Socket writer object 


iSocketsWrite 




CSocketsWrite* iSocketsWrite 




Socket resource 


iSocket 






RSocket iSocket 
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class CSocketsEngine : public MTimeOutNotify 




Server socket resource. 


iSocketServ 






RSocketServ iSocketServ 




DNS name resolver 


iResolver 






RHostResolver iResolver 




DNS Lookup result. 


iNameEntry 


TNameEntry iNameEntry; 




DNS Lookup result. 


iNameRecord 




TNameRecord iNameRecord; 




Timer active object 


iTimer 




CTimeOutTimer* iTimer 




Server address 


iAddress 






TlnetAddr iAddress; 




Port number for connect. 


iPort 






TlntiPort 




Server name 


iServerName 




TBuf<KMaxServerNameLength> iServerName 




Local Status tracking variable 


IStatus 


TRequestStatus iStatus; 



The contents of this material are confidential and proprietary to Bitfone Corporation and may not be 
reproduced, published, or disclosed to others without the prior written consent of Bitfone. 
© 2002 Bitfone Corporation. 



-59- 



Bitfone 



mProve Download Agent Integration Code 
Architecture For The Nokia 7650 



Date: 10/17/2002 



5.4.3 CSocketsWrite 



class CSocketsWrite 


: public MTimeOutNotify 


An instance of class CSocketsWrite is an object responsible for sending data through the Symbian sockets module 


to the server. 






Creates CSocketsWrite object with observer aConsole and resource aSocket. Using 


Constructor 


two-phase construction. 




CSocketsWnte(MUINotify& aConsole, RSocket& aSocket); 




Create CSocketsWrite object with observer aConsole, socket resource aSocket, using 


NewL 


two-phase construction. Return pointer to object. 




static CSocketsWrite* NewL(MUINotify& aConsole, RSocket& aSocket); 




Create CSocketsWrite object with observer aConsole, socket resource aSocket, using 


NewLC 


two-phase construction. Push object onto cleanup stack. Return pointer to object. 




static CSocketsWrite* NewLC(MUINotify& aConsole, RSocket& aSocket); 




Perform second phase construction of the CSocketsWrite. This includes initializing 


ConstructL 


timer and write socket state. 




void ConstructL(); 




Destory object and all resources owned by it. 


Destructor 




. ~CSocketsWrite(); 




Checks for socket status and send buffer condition for validity. Prepare populate the 


IssueWriteL 


send buffer with data. Calls SendNextPacket to actually send data through socket. 




void IssueWriteL(const TDesC8& aData); 




Initiates cancel procedure. Terminates timer object 


Cancel 




void Cancel() 


TimerExpired 


Checks for timer expiration, and issue message accordingly. 


void TimerExpiredO; 


SendNextPacket 


Writes the send buffer to socket. 
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class CSocketsWrite 


: public MTimeOutNotify 


void SendNextPacketQ; 


Sync_SendNextPacket 


Perfomes synchronous data sending procedure, 
void Sync_SendNextPacketO; 


TWriteState 


State of the Write socket. 

enum TWriteState {ESending, EWaiting ,ECommsFaiIed}; 


KWriteBufferSize 


Size of write buffer. The guideline for this is defined by the protocol requirements. 


iSocket 


Socket resource 
RSocket& iSocket; 


iConsole 


Observer object for displaying and logging messages for socket writing. 


MUTNotify& iConsole; 


iTransferBuffer 


Accumulate data to send in here 
TBuf8<KWriteBufferSize> iTransferBuffer 


iWriteBuffer 


Holds data currently being sent to socket 
TBuf8<KWriteBufferSize> iWriteBuffer 


iTimer 


Timer object 

CTimeOufTimer* iTimer, 


iTimeOut 


Define limits for time out condition 
Tint iTimeOut; 


iWriteStatus 


Holds the Socket write state. 
TwriteState iWriteStatus 


iStatus 


Holds system status for write socket 
TrequestStatus iStatus 
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5.4.4 CsocketsRead 



class CSocketsRead : public MTimeOutNotify 



An instance of class CSocketsRead is an object responsible for receiving data through the Symbian Sockets 
module from the server 



TimerExpired 



Creates CSocketsRead object with observer aConsole and resource aSocket. 
Using two-phase construction. 

CSocketsRead(MUINotify& aConsole, RSocket& aSocket); 

Create CSocketsRead object with observer aConsole, socket resource aSocket, 
using two-phase construction. Return pointer to object. 

static CSocketsRead* NewL(MUTNotify& aConsole, RSocket& aSocket); 

Create CSocketsRead object with observer aConsole, socket resource aSocket, 
using two-phase construction. Push object onto cleanup stack. Return pointer to 
object. 

static CSocketsRead* NewLC(MUINotify& aConsole, RSocket& aSocket); 

Destory object and all resources owned by it. 

-CSocketsReadO; 

Perform second phase construction of the CSocketsWrite. This includes 
initializing timer and write socket state. 

void ConstructL(); 

Initiates cancel procedure. Terminates timer object 
void Cancel(); 
Initiate Socket reading, 
void Start(); 

Checks for timer expiration, and issue message accordingly, 
void TimerExpiredO 

Perform Socket read and store data into read buffers. 
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class CSocketsRead : 


: public MTimeOutNotify 


void IssueReadL() 


ReadCompletedL 


Transfer read date from receive buffer into shadow buffer 


void ReadCompletedL(TDesC8 &aBuffer, Tint aLength); 




Reset shadow buffer start and end pointers 


ResetRecvBuffer 




void ResetRecvBufferQ* 




Download agent core request for data from shadow buffer. Returns aLength data 


RecvMessageL 


from Shadow buffer. 




TUint RecvMessageL(char *aMessage, unsigned int aLength); 




Download agent core request for data from shadow buffer. Returns as many bytes 


RecvMessageNoBIockL 


available in shadow buffer up to length aLength 




TUint RecvMessageNoBlockL(char *aMessage, unsigned int aLength); 




Size of write buffer. 


KReadBufferSize 






enum { KReadBufferSize = 4096 }; 




Read Socket states. 


EReadState 


enum EReadState {EReading, EReadDone, EReadError}; 




Socket to read data from 


iSocket 






RSocketA iSocket 




Observer object for displaying and logging messages for socket reading. 


iConsole 


MUTNotify& iConsole 




Buffer for receiving data 


iBuffer 




TBuf8<KReadBufferSize> iBuffer 




Returns length of data read. 


iDummyLength 


TSockXfrLength iDummyLength 


iRecvBuffer 


Shadow circular buffer to accumulate received data for download agent use. 
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class CSocketsRead : 


: public MTimeOutNotify 


TBuf8<KBufferSize> iRecvBuffer; 




Shadow buffer data starts address. 


iRecvBufferbegin 






Tint iRecvBuffer begin 




Shadow buffer data end address. 


iRecvBufferend 






Tint iRecvBuffer end 




Timer object 


iTimer 




CTimeOutTimer* iTimer; 




Define limits for time out condition 


iTimeOut 






Tint iTimeOut; 




Read Socket status 


iReadState 






EReadState iReadState; 




Holds system status for read socket 


iStatus 




TRequestStatus iStatus; 
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5.4.5 CTimeOutTimer 



class CTimeOutTimer : public CTimer 



An instance of class CTimeOutTimer is an object that notifies other objects of elapsed time. 

Constructs a CtimeOufTimer object with apriority and observer aTimeOutNotify using 
two phase construction. Return pointer to the object. 

NewL 

static CTimeOutTimer* NewL(const Tint aPriority, MTimeOutNotify& 
aTimeOutNotify); 

Constructs a CtimeOutTimer object with apriority and observer aTimeOutNotify using 
two phase construction. Pushes the object onto the cleanup stack. Returns pointer to 
NewLC me ob J ect - 

static CTimeOutTimer* NewLC(const Tint aPriority, MTimeOutNotify& 
aTimeOutNotify); 

Destroys object and releases all resources owned by it. 

Destructor 

~CTimeOutTimer(); 

Service the active object when iStatus is set to pending. 

RunL 

virtual void RunL(); 

Constructs CtimeOutTimer with apriority and observer aTimeOutNotify using two- 
Constructor P hase construction. 

CTimeOutTimer(const Tint aPriority, MTimeOutNotify& aTimeOutNotify); 
Performs second phase construction. 

ConstructL 

void ConstructLO; 

Reference an MtimeOutNotify object. 

iNotify 

MTimeOutNotify& iNotify; 
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5.4.6 MTimeOutNotify 
class MtimeOutNotify 

An instance of class MtimeOutNotify is an object which implements the timeout function 
TimerExpired virtual void TimerExpired() = 0; 
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